hap-controller
Advanced tools
This library allows you to build a HomeKit controller, capable of discovering and controlling both Wi-Fi and BLE devices.
Use npm to install the package:
npm install hap-controller
# OR
yarn add hap-controller
The IP and BLE APIs are very similar and only differ where it makes sense, given protocol differences.
const {BLEDiscovery, IPDiscovery} = require('hap-controller');
const ipDiscovery = new IPDiscovery();
ipDiscovery.on('serviceUp', (service) => {
// ...
});
ipDiscovery.start();
const bleDiscovery = new BLEDiscovery();
bleDiscovery.on('serviceUp', (service) => {
// ...
});
bleDiscovery.start(); // pass true if disconnected events are needed
const {GattClient, HttpClient} = require('hap-controller');
const ipClient = new HttpClient(id, address, port);
ipClient.identify().then(() => {
// ...
}).catch((e) => console.error(e));
const bleClient = new GattClient(id, peripheral);
bleClient.identify().then(() => {
// ...
}).catch((e) => console.error(e));
const {GattClient, HttpClient} = require('hap-controller');
const ipClient = new HttpClient(id, address, port);
ipClient.pairSetup(pin).then(() => {
// keep this data
console.log(JSON.stringify(ipClient.getLongTermData(), null, 2));
}).catch((e) => console.error(e));
const bleClient = new GattClient(id, peripheral);
bleClient.pairSetup(pin).then(() => {
// keep this data
console.log(JSON.stringify(bleClient.getLongTermData(), null, 2));
}).catch((e) => console.error(e));
const {GattClient, HttpClient} = require('hap-controller');
const ipClient = new HttpClient(id, address, port, pairingData);
ipClient.listPairings().then(() => {
// ...
}).catch((e) => console.error(e));
ipClient.removePairing(identifier).then(() => {
// ...
}).catch((e) => console.error(e));
const bleClient = new GattClient(id, peripheral, pairingData);
bleClient.listPairings().then(() => {
// ...
}).catch((e) => console.error(e));
bleClient.removePairing(identifier).then(() => {
// ...
}).catch((e) => console.error(e));
const {GattClient, HttpClient} = require('hap-controller');
const ipClient = new HttpClient(id, address, port, pairingData);
ipClient.getAccessories().then((accessories) => {
// ...
}).catch((e) => console.error(e));
const bleClient = new GattClient(id, peripheral, pairingData);
bleClient.getAccessories().then((accessories) => {
// ...
}).catch((e) => console.error(e));
const {GattClient, GattUtils, HttpClient} = require('hap-controller');
const ipClient = new HttpClient(id, address, port, pairingData);
ipClient.getCharacteristics(
['1.10'],
{
meta: true,
perms: true,
type: true,
ev: true,
}
).then((characteristics) => {
// ...
}).catch((e) => console.error(e));
ipClient.setCharacteristics({'1.10': true}).then(() => {
// ...
}).catch((e) => console.error(e));
const bleClient = new GattClient(id, peripheral, pairingData);
bleClient.getCharacteristics(
[
{
serviceUuid: '...', // the "type" property
characteristicUuid: '...', // the "type" property
iid: 10,
format: 'bool', // if known
},
],
{
meta: true,
perms: true,
type: true,
ev: true,
}
).then((characteristics) => {
// ...
}).catch((e) => console.error(e));
bleClient.setCharacteristics(
[
{
serviceUuid: '...', // the "type" property
characteristicUuid: '...', // the "type" property
iid: 10,
value: GattUtils.valueToBuffer(true, 'bool'),
},
]
).then(() => {
// ...
}).catch((e) => console.error(e));
const {GattClient, HttpClient} = require('hap-controller');
const ipClient = new HttpClient(id, address, port, pairingData);
ipClient.on('event', (ev) => {
// ...
});
ipClient.on('event-disconnect', (subscribedList) => {
// ...
});
let connection;
ipClient.subscribeCharacteristics(['1.10']).then((conn) => {
connection = conn;
// ...
}).catch((e) => console.error(e));
ipClient.unsubscribeCharacteristics(['1.10'], connection).then(() => {
// ...
}).catch((e) => console.error(e));
const bleClient = new GattClient(id, peripheral, pairingData);
bleClient.on('event', (ev) => {
// ...
});
bleClient.on('event-disconnect', (subscribedList) => {
// ...
});
bleClient.subscribeCharacteristics(
[
{
serviceUuid: '...', // the "type" property
characteristicUuid: '...', // the "type" property
iid: 10,
format: 'bool', // if known
},
]
).then(() => {
// ...
}).catch((e) => console.error(e));
bleClient.unsubscribeCharacteristics(
[
{
serviceUuid: '...', // the "type" property
characteristicUuid: '...', // the "type" property
},
]
).then(() => {
// ...
}).catch((e) => console.error(e));
Examples of all of the APIs can be found in the GitHub repo.
If you have issues pairing the device with this adapter please try to pair it with the normal iOS Apple Home App. If this do not work then something is weird with the device and then also this adapter can not help. Pot try a reset, but else there is not chance.
This is currently that way for some Tado Door Locks as example. They need to be paired using the Tado App which is somehow registering the device into Apple Home, but not via an official pair process.
Additional also Nuki 3 Locks (BLE) are not possible to pair because they use Hardware Authentication components that are not publicly documented by Apple.
For Netatmo a user found out how pairing could be possible when it had issue. See https://github.com/Apollon77/ioBroker.homekit-controller/issues/233#issuecomment-1311983379
apt update && apt dist-upgradesudo hciconfig hci0 resetuname -a and lsusbsudo hcidump -t -x >log.txt (in a second shell additionally to run the script)When you have issues and want to report an Issue (see below) then enhanced debug log is always helpful.
Please start your application using
DEBUG=hap* node myprocess.js
and post the console log also in the issue. This will generate a log on protocol level.
Please feel free to open an issue or a pull request if you find something that could use improvement. For Issues please consider to directly provide debug loggins (see above).
close method to tear down all connections that are potentially openoptions parameter in constructor. You must call close() if you do not need the instance any longerFormer versions published by @mrstegeman
FAQs
Library to implement a HAP (HomeKit) controller
The npm package hap-controller receives a total of 89 weekly downloads. As such, hap-controller popularity was classified as not popular.
We found that hap-controller demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.